Requested by Kyle Crawshaw · Slack thread

Implements client-side x402 v2 support, including the upto scheme. Server/facilitator and contracts are out of scope — this is the CLI client only. Closes ENG-2067.

Before / After

Before: wallet x402 <verb> <url> only spoke x402 v1 with the fixed-price exact scheme (EIP-3009 transferWithAuthorization). pickAccept hard-filtered the server's offers to scheme === 'exact' and silently dropped everything else, so a server that advertised an upto 402 was simply reported as "no compatible payment option" — the request failed.

After: the CLI detects v1 vs v2 from the advertised x402Version and routes accordingly (v1 servers keep working unchanged). For a v2 upto 402 it signs a Uniswap Permit2 permitWitnessTransferFrom authorization up to the advertised maximum; the facilitator then settles the actual usage (which may be less than the max, or zero for a $0 settle). The CLI surfaces the real settled amount from the response.

How

• Scheme/version registry (src/lib/x402/handlers.ts): a SchemeHandler interface (version, scheme, canHandle(accept, chainId), buildPayload(accept, ctx) -> { headerName, headerValueBase64 }). The existing EIP-3009 logic is refactored into an exact@v1 handler (behavior preserved); a new upto@v2 handler builds the Permit2 payload. selectHandler picks the first handler that supports an offered {scheme, network} on the configured chain.
• v2 transport (src/lib/x402/protocol.ts): parses both v1 (maxAmountRequired) and v2 (amount) challenges onto one normalized field; reads the base64 PAYMENT-REQUIRED challenge (header or body); emits PAYMENT-SIGNATURE; decodes PAYMENT-RESPONSE including the actual amount. CAIP-2 helpers map eip155:<id> ↔ chain id and reconcile against the CLI's --network.
• Permit2 signing (src/lib/x402/permit2.ts): named constants for the canonical Permit2 (0x0000…78BA3) and the x402UptoPermit2Proxy spender (0x4020…0002); EIP-712 types with the Witness(to, facilitator, validAfter) ordering; random 256-bit nonce, deadline/validAfter handling; signed via viem signTypedData (no new crypto dep).
• Allowance preflight + approve (walletX402.ts): reads the payer's ERC-20 allowance for the canonical Permit2 before signing; if short, offers to send the one-time approve (prompt, or auto with --x402-approve-permit2 / -y). Also handles a 412 from the facilitator with a clear "allowance required" message.
• Wiring (walletX402.ts): removed the exact-only filter; threshold/auto-pay compares against the authorized max for upto; the "no compatible payment option" error now lists exact@v1, upto@v2; the settled amount from the v2 response is displayed.

Files touched: src/lib/x402/protocol.ts, src/lib/x402/permit2.ts (new), src/lib/x402/handlers.ts (new), src/commands/walletX402.ts, tests/x402-protocol.test.ts, tests/x402-upto.test.ts (new), README.md.

Testing

• npm test — 43 passed (6 files). New/updated coverage: v1+v2 challenge parse, CAIP-2 parse/match, handler selection (upto now selectable, unsupported schemes rejected), upto payload encode (asserts exact field names/shape and string types), Permit2 typed-data construction recovering to the signer, and the missing-facilitatorAddress error path.
• npm run build (tsc) — clean, no errors. No lint config in the repo.

Caveats / follow-ups

• Witness ordering — confirmed. The Witness(address to, address facilitator, uint256 validAfter) member order was verified against the deployed x402UptoPermit2Proxy source (WITNESS_TYPEHASH = keccak256("Witness(address to,address facilitator,uint256 validAfter)")). It lives as a single source-of-truth constant (PERMIT2_UPTO_TYPES in permit2.ts) if it ever needs to change.
• Permit2 domain has no version. The task brief suggested a version: "1" domain field, but the canonical Uniswap Permit2 EIP712Domain is name-only (name, chainId, verifyingContract) — adding a version would change the domain separator and produce a signature the contract/facilitator rejects. I followed the on-chain reality (name-only) and documented this decision at the signer.
• exact@v2 scoped out. The v2 framing of the EIP-3009 exact payload isn't pinned down in the spec available, so rather than guess a payload shape that signs real value, it's left as a clearly-marked TODO in the handler registry. upto@v2 is the solid v2 deliverable. Easy follow-up once the exact@v2 payload shape is confirmed.
• The Permit2 approve is sent for maxUint256 (standard one-time unlimited approval, matching common Permit2 UX). If a scoped approval is preferred, that's a one-line change.

🤖 Generated with Claude Code

https://claude.ai/code/session_012td7BjwxkhNazzdcVTGn74

Generated by Claude Code